Sortwell™ User Guide

Sortwell sorts a folder of scans into one folder per batch, using batch cards. It is made for the Easy Index Workflow: before each group of photos you scan (or capture on a copy stand) a colored card that says the batch's date, its number and its subject. Sortwell finds every card, reads what it says, makes a folder named from it, and moves the card and the photos after it, up to the next card, into that folder.

One folder of scans                      After Sortwell
  Scan-001  (batch card)               1982-10-31-Halloween-0001
  Scan-002 ... Scan-004               Scan-001 (the card), Scan-002 ... Scan-004
  Scan-005  (batch card)               1997-12-25-Christmas-0002
  Scan-006 ... Scan-007               Scan-005, Scan-006, Scan-007

Sortwell comes two ways, with one license for both:

The Lightroom Classic plug-in, for photos already in your catalog, such as tethered captures: Library > Plug-in Extras > Sort batch cards into folders.
The Sortwell app, for Windows and Mac. It opens in your web browser and doesn't need Lightroom. Use it for scans that aren't in Lightroom, or to sort a folder before you import it.

Nothing moves until you have checked what each card says and clicked Sort into folders, and every run can be undone.

The review screen also shows the folder the batch folders go in, with a button to change it, and a Copy, rather than move tick box: tick it to copy the photos into the batch folders and leave the originals where they are.

Making batch cards Sortwell can read

Use solid, colored card stock in any color (pink, yellow, blue, green, orange …). White or grey cards look too much like the back of a print.
Put the card designator in the middle of each card: a circle with two opposite quarters filled in black (top left and bottom right), printed or drawn, about the size of a coin. This is how Sortwell tells a batch card from a photo, whatever color the card is. You can use a mark of your own instead (see Settings).

Along the top of the card, write each thing after a printed word saying what it is, with the date as year-month-day and 00 for a part you don't know:

Batch: 0001     Date: 1982-10-31     Subject: Halloween
Batch: 0003     Date: 1976-03-00     Subject: Spring Break      (March 1976, day not known)
Batch: 0004     Date: 1975-00-00     Subject: baby              (only the year is known)

Use a dark pencil or marker, in clear letters. Sortwell reads printed numbers very well and clear handwriting well. Joined-up or faint handwriting is harder: the review lets you fix anything it misread, or you can have the hard ones read online with your own API key (see below).
The words before each part can be Batch, Number or No.; Date; and Subject, Description or Event. Without them Sortwell still finds the parts: a number on its own is the batch, a date is the date, and the rest is the subject.
The date can also be written 6/21/1987, 21 June 1987, June 1987, 1987, a range (1985-88), a decade (1970s) or a guess (circa 1962, c. 1962).
If you scan the back of each card too, that's fine: a blank card straight after a card is taken as its back and goes into the same folder.
Photos before the first card stay where they are.

Reading hard handwriting online (optional)

For cards this computer can't read well, Sortwell can also ask an online service: Claude (Anthropic), OpenAI or Google Gemini, with your own API key, so what it costs goes on your own account (usually a fraction of a cent per card). Only the batch cards are sent, never your photos.

Lightroom Classic: File > Plug-in Manager > Sortwell > Reading hard handwriting online. The app: under Reading the cards, click Read hard handwriting online.
Choose the service, then Enter API key (or paste it in the app) and save. Get a key opens the service's page for API keys, and Getting an API key below has the steps. A chat subscription (such as ChatGPT Plus or Claude Pro) does not include an API key.
When: Only cards this computer can't read well (a part is missing, or the reader wasn't sure) or Every card.
A key saved for Labelwell or Datewell is used too. The Lightroom plug-in and the app share these settings.
The review says "read online" for each card the service read. If the service can't be reached, the cards keep what this computer read.
To stop, choose None as the service or click Remove key. On Google's free tier, Google may use what is sent to improve its products; on a paid key it does not.

Getting an API key

An API key is a long password that lets Sortwell use your account with the service. A chat subscription such as Claude Pro or ChatGPT Plus does not include one: the key comes from the service's developer site, which has its own sign-in and its own pay-as-you-go billing. You only need one key, from one service, and if you already saved one in Labelwell or Datewell, Sortwell uses it too. The sites change their menus from time to time, so a button may be worded a little differently from what is written here.

Which one to choose

Claude (Anthropic) is the one we use in our own studio. It reads handwriting best in our tests, costs a fraction of a cent per card, and what you send on a paid account is not used to train its models.
Google Gemini has a free key with no card needed, which is a good way to try reading online. On the free key, Google may use what you send to improve its products, and people at Google may look at it, so don't use the free key on cards you'd want kept private. With billing turned on, Google doesn't use what you send.
OpenAI works the same way as Claude: a paid account with credit added first.

Claude (Anthropic)

Go to console.anthropic.com and sign up (or sign in) with your email or Google account. This is a separate account from a claude.ai chat subscription, though it can use the same email.
Open Settings > Billing and click Buy credits. Add a small amount; $5 is the least you can add and lasts a long time for reading cards. Reading online won't work until the account has credit.
Open Settings > API keys and click Create key. Give it a name you'll recognize, such as Sortwell.
Click Copy and paste the key into Sortwell straight away (it starts with sk-ant-). The site shows the key only once; if you lose it, delete it there and create a new one.

Google Gemini

Go to aistudio.google.com and sign in with your Google account. The first time, accept the terms. A work or school Google account may not be allowed to make keys; a personal Gmail account works.
Click Get API key (or go straight to aistudio.google.com/apikey), then Create API key. If it asks about a project, choose to create it in a new project.
Copy the key (it starts with AIza) and paste it into Sortwell.
The free key has daily limits, about a thousand or so readings a day, which is plenty for most jobs. To lift the limits and keep your cards out of Google's product improvement, turn on billing for the key's project in AI Studio.

OpenAI

Go to platform.openai.com and sign up (or sign in). This is separate from a ChatGPT subscription.
Open Settings > Billing and add credit; $5 is the usual least amount.
Open API keys (platform.openai.com/api-keys) and click Create new secret key. Give it a name such as Sortwell.
Copy the key (it starts with sk-) and paste it into Sortwell straight away; it is shown only once.

Keeping your key safe

Treat the key like a password: don't email it, post it or put it in a screenshot. Sortwell keeps it on this computer only. If you think someone else has seen it, delete it on the service's site, create a new one, and paste the new one into Sortwell. The service's own billing page shows what you have spent, and you can set a spending limit there.

In Lightroom Classic

In the Folders panel, click the folder of scans (or select the photos to sort).
Library > Plug-in Extras > Sort batch cards into folders.
Check the settings (see below) and click Find the cards. Sortwell reads each card from its own file (for camera raw files, the preview inside it), or from Lightroom's preview if the file can't be opened.
The review shows each card, what Sortwell read on it, and the folder it will make. Fix any date, number or subject that was misread; the folder name changes as you type. Untick a "card" that isn't one: its photos then stay with the batch before it.
Click Sort into folders.

Sortwell moves the files (and their .xmp sidecars) on disk, adds them to the catalog at their new places, and puts back what the catalog knew about each photo: its pick or reject flag, stars, keywords, title, caption and the other IPTC fields, GPS location, its Develop settings (edits, crop and rotation) and the collections it is in. Then it removes the old entries, so the Folders panel shows the batch folders with their photos. (With Copy, rather than move, the originals stay in the catalog as they were, and the copies are added with the same catalog data.)

Afterwards Sortwell opens the folder the batch folders went in. If that folder isn't in the catalog's Folders panel yet, the batch folders show at the top level instead: right-click one of them > Show Parent Folder to see them inside it. (Lightroom doesn't let plug-ins add a folder that has no photos in it.)

What can't be carried over, because Lightroom doesn't let plug-ins set it: virtual copies, stacks, Develop snapshots and the history list, links to publish services, and other plug-ins' fields. Sortwell tells you before anything moves if any of the photos have these. Tethered captures and fresh scans usually have none of them.

On Lightroom Classic older than 14.3, Sortwell can't remove the old entries itself, and they show as missing photos in the scan folder. Right-click the folder > Synchronize Folder and tick "Remove missing photos from catalog" to clear them.

The cards get the keyword Sortwell > Batch card, so you can find them all in the Keyword List. Like all keywords our plug-ins add, it is never exported with your photos.

A card Sortwell misses, or a photo it takes for a card

Select the photo, then Library > Plug-in Extras > Mark as a batch card or Not a batch card, and run Sortwell again. Clear the batch card marking takes the mark off.

The Sortwell app

Start Sortwell (Windows: Start menu > Sortwell; Mac: Applications > ThePictureOrg > Sortwell). It opens in your web browser and works only on this computer.
Click Choose and pick the folder of scans, or type or paste its path in the box.
Check the settings on the left and click Find the cards.
Check each card's date, number and subject, as above, then click Sort into folders.
Show the folders opens the folder they went into.

The app reads JPEG, TIFF, PNG and camera raw files (for raw files it uses the preview picture inside the file).

To bring the sorted folders into Lightroom Classic afterwards, import the folder the batches went into as usual, with "Include Subfolders" on.

Settings

Setting	What it does
Finding the batch cards	Cards with the designator graphic (the usual way): a photo with the card designator on it is a card, whatever its color. The first photo is a card: for cards without a designator; Sortwell learns the cards' color from the first photo and finds the others of that color. Cards of any color: any photo that is mostly one solid color counts as a card.
Designator	Empty for the built-in one (the circle with two black quarters). To use a mark of your own, click Choose and pick a picture of it: dark on white (or on a transparent background), cropped close around the mark. Type or paste its path if you like. Built-in goes back to the circle.
Color match	For the two ways without a designator. Normal suits most cards. Loose for faded or unevenly lit cards; Strict if photos with a big patch of a similar color are taken for cards.
Photo order	File name (Scan-001, Scan-002 …, numbers in order, so 2 comes before 10) or Capture time (in the app: Date modified).
Dates like 6/7/87	Month first (US: June 7) or Day first (6 July). A date like 21/6/87 is read correctly either way, since 21 can't be a month.
Batch numbers	As written (7), three digits (007) or four digits (0007, the default), so the folders sort in order.
Folder names	The pattern for the folder names. `{date}`, `{batch}` and `{description}` (the subject) are replaced by what the card says; a part the card doesn't have is left out with the text around it. The default is `{date}-{description}-{batch}`, for example "1982-10-31-Halloween-0001".
Where the batch folders go	Inside the scan folder, next to it, or in a folder you choose (type or paste a path, or click Choose).

Finishing the batch folders

When a batch's photos are in order, Finish the batch folders makes each batch folder final:

the folder's date goes into every photo as its date taken (at noon). A part written 00 is unknown: 1982-10-00 is written as October 1982, 1982-00-00 as 1982. A circa year (c1955) is written as that year; a decade (1960s) or a span of years (1975-1978) writes no date;
the folder's event name (the card's subject) is added to every photo as a keyword;
the batch number comes off the folder's name: "1982-10-31-Halloween-0001" becomes "1982-10-31-Halloween";
the photos are renamed with the folder's new name and a four-digit number: 1982-10-31-Halloween-0001.jpg, -0002 and so on. Two folders that end up with the same name are joined into one and numbered on.

The date and the keyword are written into each photo (for camera raw files, into the .xmp sidecar beside it), so other programs see them too. Batch cards still in a folder keep their names and are left out of the numbering.

Lightroom Classic: click the folder the batch folders are in (or select the batch folders) in the Folders panel, then Library > Plug-in Extras > Finish the batch folders. The photos are numbered in the order Lightroom shows them at that moment: sort the grid the way you want first (View > Sort, or drag them into a custom order). Photos a filter or a closed stack hides are numbered last. Each photo keeps its flags, stars, keywords, edits and collections.
The app: menu > Finish the batch folders, then the folder the batch folders are in, then Finish. The photos are numbered in file-name order.

A preview shows every folder's new name, date and keyword, and the first and last new file names, before anything changes. Undo a Sortwell run puts the names, folders, dates and keywords back.

When you're done with the batches: deleting the cards

When you have finished with the batches (captions, rotation and so on), the cards can go.

Lightroom Classic: click the scan folder (or the folder the batches are in), then Library > Plug-in Extras > Delete the batch cards. Only the batch cards (the photos with the keyword Sortwell > Batch card) go to the Recycle Bin (Windows) or the Trash (Mac), with their .xmp sidecars, and come out of the catalog. No other photo is touched, so you can still get a card back from the Recycle Bin or Trash.
Or, to look at them first along with photos you rejected yourself: Library > Plug-in Extras > Mark batch cards and rejects for deletion. The cards are flagged Rejected, along with any photos you rejected yourself. Then Photo > Delete Rejected Photos > "Delete from Disk". Lightroom shows you what will be deleted and asks first.
The app: menu > Remove or delete the batch cards, then for a run either Move out (the cards go into one folder named "Removed batch cards", next to the batch folders, so you can look before you delete that folder; this can be undone too) or Delete (just the cards go to the Recycle Bin or Trash).

Undo

A run that copied the photos: undo deletes the copies (only where the original is still there) and the batch folders, and leaves the originals alone.
Lightroom Classic: Library > Plug-in Extras > Undo a Sortwell run moves every file of a run back where it was, puts it back in the catalog with its flags, keywords and edits, and deletes the batch folders the run made once they are empty.
The app: the Undo button (or menu > Undo) does the same for the files.

Each run keeps a small undo file in your PictureOrg folder, "Sortwell-undo". A file that was moved or renamed after the run is left where it is, and the undo says so.

Updates

Automatic check: once a day Sortwell looks up the current version number on thepictureorg.com's download service, in the background when Lightroom starts and when you run it. Only that small version list is fetched: nothing about your computer, your photos or your license key is sent.
When a new version is out: the next time you run Sortwell, a message says so once per Lightroom session: Install now (or Download), Not now (asks again next time you start Lightroom) and Skip this version (stays quiet until a later version comes out). Nothing is downloaded or installed until you click.
Install now: Sortwell downloads the update, checks that it arrived whole and unchanged, that it carries The Picture Org's release signature and that it is newer than the version you have, and installs it into its own folder, with a progress bar. Then quit and restart Lightroom Classic to start using it. If anything goes wrong, every file is put back as it was.
Download: opens the installer download in your browser; close Lightroom Classic and run the new Setup program (Windows) or Install Sortwell (Mac). Your settings and license key are kept either way.
Plug-in Manager > Updates: shows your version and whether a newer one is out, with Check now, Install update, Download installer and What's new. Untick Check for updates automatically to turn the daily check off; Check now still works. When an update can't be installed from inside your version, the panel says to use Download installer for that one.
The app checks once a day when it opens, and Check for updates checks at any time. When a new version is out, a bar lets you install it (the app installs it into its own folder, then restarts itself), download the installer, or see what's new. The plug-in and the app update separately: each installed copy has its own files.

Updates within the major version are complimentary.

License and free trial

Free trial: every feature works for 21 days on each computer. The Plug-in Manager panel and the app show how many days are left, for example "Free trial: 14 days left".
After the trial: for 7 more days Sortwell still works, with a reminder. After that, finding and reading the cards still works, and sorting needs a license key. When a license key is needed, Sortwell says "the free trial has ended" and offers Buy a license and Enter key....
Buying: click Buy a license in the License section of File > Plug-in Manager (select Sortwell), or on the license line at the top of the app, or go to thepictureorg.com/tools. One license is for one person on up to 2 computers, covers the app and the Lightroom plug-in, and includes complimentary updates within the major version (a version 1 key works for every 1.x release).
Entering your key: paste the whole key from your order email into the License key box in the Plug-in Manager and click Enter key, or click the license line at the top of the app. Spaces and line breaks don't matter. It then says "Licensed to" and your name. The key is checked on this computer: nothing is sent anywhere, and no internet connection is needed.
Plug-in and app: one license, one free trial. The plug-in and the app share the key and the 21-day count on each computer, so a key entered in either unlocks both.
New computer: click Remove license from this computer on the old one (it asks first), then enter the key on the new one.
Where the key is kept: in your user account, not in the program's folder, so it stays through updates and reinstalling: %LOCALAPPDATA%\PictureOrg on Windows, ~/Library/Application Support/PictureOrg on a Mac.

Help

No cards were found: check that the cards have the designator on them (or, for cards without one, choose "The first photo is a card" or "Cards of any color", and try Color match "Loose"). With a designator of your own, check that its picture is cropped close and is the same mark as on the cards.
A photo was taken for a card: untick it in the review (or mark it "Not a batch card" in Lightroom). Without a designator, try Color match "Strict".

Check my setup (in the app's menu, or in File > Plug-in Manager with Sortwell selected) checks that everything Sortwell needs works on this computer, and shows the result as text you can copy or save.
Create an error log (in the app's menu, or Library > Plug-in Extras > Sortwell: Create an error log) saves a text file on your Desktop with what Sortwell did. Email it to The Picture Org with a few words about what went wrong. File names are in it; your photos aren't, and nothing is sent by itself.

Sortwell reads the cards with RapidOCR and finds them with OpenCV (and, only if you set it up, the online service you chose). See NOTICE.txt.